t Recommended Practices

Flushing Datafiles  *487*

When an application saves data to a datafile using the cluster-write or cluster-replace primitives, the data is not necessarily written to disk immediately. It is placed in a buffer in memory, and only when the buffer becomes full is the data copied to disk and the buffer emptied. This is a common practice in all file management software, since it improves performance by minimizing the number of times that the disk is accessed. However, it also means that your datafile is not up-to-date until the file buffer is emptied (i.e. flushed) to disk.

The primitives db-get-flush and db-set-flush allow you to flush  the datafile's buffer after every primitive that changes the datafile.

The following method flushes a datafile’s buffer after adding a new cluster:

__________________________________________________________
WARNING!

If your application crashes due to a power failure, hardware failure, or software bug, after calling either cluster-write or cluster-replace, but before the buffer was flushed, then the most recent data you attempted to store would not actually be safely saved in the datafile on the disk. It is also possible that the last byte written to disk was not the very end of a cluster; therefore, the datafile would be corrupted if the application unexpectedly terminated. 

As a safety precaution, we recommend you call the db-flush primitive in your applications, to explicitly flush the datafile’s buffer on demand. This primitive must be supplied with the database id number (DB id # in the previous example). It will flush the contents of a datafile’s buffer on to disk and return an error number indicating whether or not the primitive succeeded or failed. The best time to call db-flush is immediately after a call to either cluster-write or cluster-replace.

Note that it is not necessary to call db-flush for a datafile that is open in Shared mode. The data buffer of a shared datafile is automatically flushed after every call to cluster-write and cluster-replace.
----------------------------------------------------------

Compacting Datafiles  *488*

In an application, when new clusters are added to the datafile to build it up, they are placed within the datafile wherever adequate room is found for the cluster’s data. In most cases, new clusters are added to the end of the existing datafile. However, sometimes empty space is made available within the body of the datafile - usually the result of replacing an old cluster with a new one of a different size:

r If the new cluster is smaller than the old one, then the extra space is vacant and available for the next write to the datafile. 

r If the new cluster is larger than the old one, then the new cluster is added to the end of the datafile and the space occupied by the old cluster is left vacant.

After awhile, all this vacant space can build up to a considerable size, and can be reclaimed by compacting the datafile.

________________________________________________________
A  NOTE ABOUT PURGING AND COMPACTION:

A cluster that has been deleted (by calling cluster-delete) is not purged from the datafile until the file is compacted.
--------------------------------------------------------

The pockets of empty space as well as the space occupied by deleted clusters can be reclaimed by calling db-compact. This primitive must be supplied with the database id number (DB id# from previous examples) and will compact the datafile and return an error number, indicating whether or not the primitive succeeded.

________________________________________________________
COMPACTING TIPS:

A good time to compact a datafile is just before closing it.

A datafile cannot be compacted when open in Shared mode.
--------------------------------------------------------

The following method compacts a datafile and then closes it: